H-6763: Speak finalized Brunch responses with OpenAI - #9357

🌟 What is the purpose of this PR?

Speak finalized Brunch responses through OpenAI's dedicated Speech API. The exact canonical text already visible in Petrinaut—including a validated pending brunch_ask question—is selected once, sent unchanged for synthesis, and played while the microphone remains closed.

OpenAI Realtime continues to perform transcription only; it never generates assistant responses.

🔗 Related links

• Linear: H-6763 (internal)
• Depends on #9356
• Stack: #9346 → #9355 → #9356 → H-6763: Speak finalized Brunch responses with OpenAI #9357
• #9297 is historical evidence only and is unchanged.

🚫 Blocked by

• #9356 and its downstack prerequisites

🔍 What does this change?

• Selects only finalized canonical assistant text and schema-validated brunch_ask.input.question values.
  • Reasoning, partial text, tool output, malformed asks, other tools, and non-assistant roles are excluded.
  • Questions come from structured AI SDK parts, never DOM scraping.
  • The real Brunch ask integration test proves an awaiting question is emitted without duplicate visible assistant text.
• Assigns every speakable segment stable message/part identity and an exact-text fingerprint.
  • The browser sends { segmentId, text }.
  • The server recomputes the fingerprint and rejects any mismatched or malformed request.
• Adds the app-owned /api/voice/speech edge.
  • It validates same-origin, content type, body size, text length, and segment identity.
  • It sends the exact selected text to OpenAI gpt-4o-mini-tts with server-fixed marin voice and MP3 output.
  • It accepts only audio/mpeg, disables caching, sanitizes upstream errors, and propagates timeouts/client cancellation.
  • It sends no content-changing instruction, “say exactly” prompt, or Realtime response.create event.
• Adds cancelable, stale-safe browser playback.
  • New generations cancel old fetch/audio work.
  • Audio elements, response streams, blobs, and object URLs are cleaned up on success, failure, cancellation, and disposal.
• Extends the half-duplex controller so the microphone stays closed throughout synthesis and playback and reopens only after speech drains and Brunch is ready.
• Keeps canonical text visible if speech fails; there is no generated or alternate speech fallback.
• Adds accessible synthesis/playback status and the required disclosure: spoken responses use an AI-generated OpenAI voice.
• Updates ADR-0009, the website README, and the Petrinaut AI-assistant guide. No provider abstraction, package dependency, lockfile change, or ElevenLabs path is added.

Stack record: direct base 7c042206e919b80ef27ce46649bfe5202005b27c; PR head b98ec4772a9702e1cba096e5604e7dc77f46706d.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

No existing documentation screenshot covers this voice surface.

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• Public production rollout is intentionally blocked on FE-1439, FE-1420, platform authentication, distributed quotas, FE-1505 telemetry, and FE-1438/FE-1440 completion/projection contracts.
• The pruned @apps/brunch-agent CI jobs cannot see the non-workspace condition-5 runner on the FE-1506: Show captures and completion while a panel elicitation runs #9346 base. Parallel PR #9348 already contains the exact tested prune fix (ade09e9c36), so this sibling stack does not duplicate it. Full-checkout Brunch tests, lint, typecheck, and build pass locally.
• The inherited Brunch docs-index check remains 6/7 because FE-1506: Show captures and completion while a panel elicitation runs #9346 references ADR-0008 from the parallel prerequisite stack.
• Transport emits 4 inherited no-await-in-loop warnings and Brunch emits 12 inherited warnings.

🐾 Next steps

Voice PR4 will add delivery caching, authoritative reload reconciliation, stale-ask recovery, authentication, distributed quotas, telemetry, retention cleanup, a kill switch, and real completion/projection evidence. It must not start until the listed platform contracts are available.

🛡 What tests cover this?

• Canonical-selection tests prove exact finalized assistant/ask selection and exclusion of reasoning, tool output, partial, malformed, and duplicate content.
• Speech-handler tests prove request bounds, exact-text forwarding, fixed server policy, media-type enforcement, sanitized errors, timeout, disconnect, and stream cancellation.
• Playback-controller tests prove cancellation, stale-generation rejection, and resource cleanup.
• Turn-controller/component tests prove queued speech ordering, microphone suppression, failure fallback, disclosure, and accessible status.
• The Brunch ask integration test proves the structured question reaches Petrinaut without duplicate assistant text.

yarn workspace @hashintel/petrinaut test:unit --run
yarn workspace @hashintel/petrinaut lint:eslint
yarn workspace @hashintel/petrinaut lint:tsc
yarn workspace @hashintel/petrinaut build
yarn workspace @apps/petrinaut-website test:unit
yarn workspace @apps/petrinaut-website lint:eslint
yarn workspace @apps/petrinaut-website lint:tsc
yarn workspace @apps/petrinaut-website build
yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit
yarn workspace @hashintel/brunch-agent-transport-aisdk lint:eslint
yarn workspace @hashintel/brunch-agent-transport-aisdk lint:tsc
yarn workspace @hashintel/brunch-agent-transport-aisdk build
yarn workspace @apps/brunch-agent test:unit
yarn workspace @apps/brunch-agent lint:eslint
yarn workspace @apps/brunch-agent lint:tsc
yarn workspace @apps/brunch-agent build
yarn workspace @local/petrinaut-arch-docs lint:arch-docs
yarn oxfmt --check apps/petrinaut-website apps/brunch-agent libs/@hashintel/petrinaut libs/@hashintel/brunch-agent

Credential-dependent checks not run: real OpenAI synthesis, remote Brunch, microphone/browser permission, exact spoken output in desktop Chrome/Edge/Safari, and deployed cancellation/failure behavior.

❓ How to test this?

1. Run yarn workspace @apps/petrinaut-website test:unit plus its lint, typecheck, and build commands above.
2. In a protected preview with OpenAI credentials and a real Brunch endpoint, complete one text turn and one voice turn.
3. Confirm finalized assistant text and a pending structured question are each spoken once and match the visible text exactly.
4. Cancel/end voice and induce a speech failure; confirm playback stops, the microphone remains safely closed until Brunch is ready, and visible text remains usable.

📹 Demo

Not included: credentialed browser/provider evidence remains an explicit acceptance requirement.